home *** CD-ROM | disk | FTP | other *** search
/ FishMarket 1.0 / FishMarket v1.0.iso / fishies / 426-450 / disk_448 / fifodev / fifo.doc < prev    next >
Text File  |  1992-05-06  |  9KB  |  226 lines
  1.  
  2.                 FIFO.DOC
  3.  
  4.          (c) Copyright 1990, Matthew Dillon, All Rights Reserved
  5.  
  6.             BIX:    mdillon
  7.             UUCP:    dillon@overload.Berkeley.CA.US
  8.  
  9.                   FIFO:
  10.  
  11.     FIFO: is like PIPE: but is based on fifo.library rather than its
  12.     own implementation.  Full master/slave support exists.  Since
  13.     FIFO: uses fifo.library, programs that require non-blocking IO
  14.     capability can access one side of a FIFO: connection via the
  15.     fifo.library instead of FIFO:
  16.  
  17.     The implementation of FIFO: and fifo.library is a billion times
  18.     better than that for PIPE:
  19.  
  20.     FIFO:<name>/<flags>
  21.  
  22.     <name>:    a valid fifo name
  23.  
  24.     name may be any combination of alpha numerics up to 64 chars long,
  25.     and is case sensitive.    FIFO: will append either "_m" or "_s" to
  26.     the name it supplies to fifo.library depending on whether master
  27.     mode or slave mode is selected.
  28.  
  29.     <flags>:    a valid combination of flags
  30.  
  31.     r   open for read
  32.  
  33.     w   open for write
  34.  
  35.     rw  open for read & write (full duplex)
  36.  
  37.     c   open in cooked mode - must be specified on one side only,
  38.         usually the slave side.  Any data received by the slave
  39.         side is cooked before continuing on to the slave.  This allows
  40.         the slave side, usually a shell and/or program, to change
  41.         between cooked and raw mode with the standard SCREEN_MODE
  42.         packet.
  43.  
  44.     e   EOF mode (when combined with 'w').  When this file handle
  45.         is closed, an EOF will be sent to the other side.
  46.  
  47.     k   KEEP mode.    If a writer opens a fifo, writes data, then
  48.         closes the fifo before a reader has a chance to open the
  49.         fifo, this flag prevents the data from being lost.
  50.  
  51.     m   select master side (else slave).  For example, the master
  52.         side writer "mw" is paired with the slave side reader "r":
  53.  
  54.             mw   -> r
  55.             mr  <-    w
  56.             mrw <-> rw
  57.  
  58.     t   tee read.  Usually specified "rt" or "mrt" depending on what
  59.         you want to monitor.  This option causes the read stream to
  60.         be a copy of available read data such that it does NOT
  61.         interfere with other readers.
  62.  
  63.         Otherwise this fifo will compete with other fifos for read
  64.         data.  For a remote shell, tee operation is not desireable
  65.         as a default but is useful to monitor the shell from an
  66.         independant program.
  67.  
  68.     s   SHELL mode, creates a separate message port for the handle,
  69.         allowing the shell & progams to find their STDERR handle.
  70.         (i.e. the open-* packet works properly).
  71.  
  72.         WARNING: use of this option increases overhead in the FIFO:
  73.         device and is generally required to be specified for the slave
  74.         side of a shell (i.e. newshell fifo:name/rwkecs)
  75.  
  76.     C   Send ^C to all (slaves or masters)
  77.     D   Send ^D to all (slaves or masters)
  78.     E   Send ^E to all (slaves or masters)
  79.     F   Send ^F to all (slaves or masters)
  80.  
  81.         You can send one or more signal to all the slaves (or masters
  82.         if 'm' is also included) using these flags.  note that it is
  83.         not necessary to open a file handle to so, specifying a
  84.         string like this:
  85.  
  86.         "FIFO:fubar/C"
  87.  
  88.         would result in sending a ^C to all fubar slaves even though
  89.         the Open() fails due to the lack of a 'r' or 'w' in the
  90.         specification.
  91.  
  92.              SEE REMCLI.C FOR EXAMPLE IMPLEMENTATION
  93.  
  94.  
  95.                    LINKED FIFOS
  96.  
  97.     FIFO: provides a full duplex connection using TWO fifo.library FIFOS.
  98.     Openning a fifo in master mode verses slave mode determines which
  99.     names are used for reading and writing.  You should note that when
  100.     a FIFO: handle is openned for both read and write, reading from the
  101.     handle actually accesses a different physical fifo than writing to
  102.     the handle.  Openning a FIFO: for only one direction ('r' *or* 'w')
  103.     results in a half duplex connection.  It is important to properly
  104.     specify the rw modes for the fifo.
  105.  
  106.          FIFO: device             fifo.library
  107.  
  108.     Open("FIFO:junk/w", 1005);              junk_s
  109.     Open("FIFO:junk/r", 1005);              junk_m
  110.     Open("FIFO:junk/rw",1005);              junk_s (w), junk_m (r)
  111.  
  112.     Open("FIFO:junk/wm", 1005);             junk_m
  113.     Open("FIFO:junk/rm", 1005);             junk_s
  114.     Open("FIFO:junk/rwm", 1005);            junk_m (w), junk_s (r)
  115.  
  116.                    REMOTE SHELL
  117.  
  118.     It is extremely easy to set up a fifo to interface a program with a
  119.     remote shell.  The FIFO: fully supports remote shells including
  120.     the ability to propogate ^C through ^F and handle stderr ("*").
  121.  
  122.     Not only that, but programs which need to be able to access the
  123.     master side of a shell in a non-blocking fashion may access the
  124.     master side directly through FIFO.LIBRARY calls.  See FIFOLIB.DOC
  125.     for the function call list, see REMCLI.C for a working example.
  126.  
  127.     1> NewShell FIFO:name/rwkecs
  128.     1> run remcli name
  129.  
  130.     Generally the shell is run off the slave side and the controlling
  131.     program is run off the master side.  The side that runs the shell
  132.     MUST specify the 's' option, as shown above.  Here is a description
  133.     of the flags used in the NewShell line:
  134.  
  135.     rw  full duplex connection.  shell 'reads' from the master and
  136.         'writes' results back to the msater.
  137.  
  138.     k   if slave side is started up first, as in the above example, any
  139.         writes it does will NOT be lost.  Not really required since the
  140.         slave side shell does not endcli itself.
  141.  
  142.     e   when slave side closes the handle, an EOF will be sent to
  143.         the master side.
  144.  
  145.     c   run slave side in COOKED mode.  FIFO: will do command line
  146.         editing on any data sent to the slave side.  You do not specify
  147.         COOKED mode for the master side.  I repeat, do NOT specify
  148.         cooked mode for the master side.  (you can't in the above
  149.         example since the master is the 'remcli' program.
  150.  
  151.         note that in COOKED mode, FIFO: echo's characters received on
  152.         the slave side back to the master, just like the console
  153.         device.
  154.  
  155.     s   SHELL support, required on the slave specification when run
  156.         from NewShell, causes the handle to get its own message port.
  157.         (required to support Open("*", ...);
  158.  
  159.     NOTE:  YOU CAN RUN 'remcli name' MULTIPLE TIMES SIMULTANIOUSLY
  160.     USING THE SAME FIFO NAME.  All remcli's talking to the same
  161.     shell will get all output from the shell and additionally be
  162.     able to issue commands.  This can be extremely useful as a
  163.     monitoring tool.
  164.  
  165.         1> run remcli name
  166.         1> run remcli name
  167.  
  168.     You can also capture all shell interaction with this:
  169.  
  170.         1> copy FIFO:name/rmt t:capture
  171.  
  172.     The 't' (TEE) specification is required to ensure you do not screw
  173.     up any other readers.  There is no limit on the number of 'readers'
  174.     monitoring a named fifo.  The RemCLI program uses the fifo.library
  175.     to access the master side and thus TEEs automatically.
  176.  
  177.     If RemCLI tries to talk to a fifo that does not exist, it will
  178.     'freeze' until the slave side does exist.  Meaning you can run
  179.     RemCLI before you start up the shell.
  180.  
  181.     CLOSING THE REMCLI WINDOW DOES NOT END THE SHELL.  You must type
  182.     'endcli' or 'endshell' to cause it to exit.  On the otherhand,
  183.     closing the remcli window and then reopenning will yield the
  184.     previous shell (which never exited).
  185.  
  186.                 PIPEING
  187.  
  188.     You can use the FIFO: device to pipe output from one program to the
  189.     input of another.  Note that you want to be sure to use the 'k' flag
  190.     in case the program generating the output generates only a little (and
  191.     is able to exit before you have a chance to start the reader).  You
  192.     also want to use the 'e' (EOF) option or the reader will not receive
  193.     an EOF, and you must make one side a master.
  194.  
  195.     1> cat >FIFO:xx/wkme
  196.     1> cat <FIFO:xx/r
  197.  
  198.     If you do not specify the 'e' EOF option then you can run multiple
  199.     program's output through the pipe sequentially, specifying the eof
  200.     option only for the last one.
  201.  
  202.     WARNING:    If you ^C the reader before it gets the EOF and exits
  203.     on its own, and if the writer is still writing, the writer will
  204.     freeze up when the fifo becomes full (requiring a reader to unfreeze
  205.     it).  Additionally, if the 'k' option is not used, even if the writer
  206.     does not freeze up there may be unwanted data left in the fifo even
  207.     though nobody is referencing it.
  208.  
  209.     1> cat <FIFO:xx/r
  210.     2> cat >FIFO:xx/wme
  211.  
  212.     To safely recover from a broken reader, the program controlling the
  213.     pipe must do the following steps:
  214.  
  215.     (1) break the writer if it has not exited (but it may be frozen,
  216.         so...)
  217.  
  218.     (2) open a reader /r and a writer /wme, then immediately close
  219.         the writer.
  220.  
  221.     (3) read from the reader until EOF.  Even if the original writer
  222.         had already exited, the fact that you open and close a dummy
  223.         one will regenerate the EOF.
  224.  
  225.  
  226.